package org.io4j.data;

import java.nio.charset.Charset;
import java.util.Collection;

/**
 * A sink for text that can be written to.
 */
public interface TextSink {

	/**
	 * Writes {@code String} representation of each element in a collection line
	 * by line using platforms's default character set.
	 * 
	 * @param lines
	 *           Lines to write; {@code null} elements produce blank lines
	 * @throws DataTransferException
	 *            if an error occurred during the operation
	 */
	void writeLines(Collection<?> lines);

	/**
	 * Writes {@code String} representation of each element in a collection line
	 * by line using character set provided.
	 * 
	 * @param lines
	 *           Lines to write; {@code null} elements produce blank lines
	 * @param charset
	 *           Character set to use
	 * @throws DataTransferException
	 *            if an error occurred during the operation
	 */
	void writeLines(Collection<?> lines, Charset charset);

	/**
	 * Writes text into this {@code TextSink} using platforms's default character
	 * set.
	 * 
	 * @param text
	 *           Text to write
	 * @throws DataTransferException
	 *            if an error occurred during the operation
	 */
	void writeText(String text);

	/**
	 * Writes text into this {@code TextSink} using character set provided.
	 * 
	 * @param text
	 *           Text to write
	 * @param charset
	 *           Character set to use
	 * @throws DataTransferException
	 *            if an error occurred during the operation
	 */
	void writeText(String text, Charset charset);
}
